.TH "Toplist handling" 3spotify "Wed Mar 28 2012" "libspotify" \" -*- nroff -*-
.ad l
.nh
.SH NAME
Toplist handling \- 
.SS "Defines"

.in +1c
.ti -1c
.RI "#define \fBSP_TOPLIST_REGION\fP(a, b)   ((a) << 8 | (b))"
.br
.in -1c
.SS "Typedefs"

.in +1c
.ti -1c
.RI "typedef void \fBtoplistbrowse_complete_cb\fP (\fBsp_toplistbrowse\fP *result, void *userdata)"
.br
.in -1c
.SS "Enumerations"

.in +1c
.ti -1c
.RI "enum \fBsp_toplisttype\fP { \fBSP_TOPLIST_TYPE_ARTISTS\fP =  0, \fBSP_TOPLIST_TYPE_ALBUMS\fP =  1, \fBSP_TOPLIST_TYPE_TRACKS\fP =  2 }"
.br
.ti -1c
.RI "enum \fBsp_toplistregion\fP { \fBSP_TOPLIST_REGION_EVERYWHERE\fP =  0, \fBSP_TOPLIST_REGION_USER\fP =  1 }"
.br
.in -1c
.SS "Functions"

.in +1c
.ti -1c
.RI "\fBsp_toplistbrowse\fP * \fBsp_toplistbrowse_create\fP (\fBsp_session\fP *session, \fBsp_toplisttype\fP type, \fBsp_toplistregion\fP region, const char *username, \fBtoplistbrowse_complete_cb\fP *callback, void *userdata)"
.br
.ti -1c
.RI "bool \fBsp_toplistbrowse_is_loaded\fP (\fBsp_toplistbrowse\fP *tlb)"
.br
.ti -1c
.RI "\fBsp_error\fP \fBsp_toplistbrowse_error\fP (\fBsp_toplistbrowse\fP *tlb)"
.br
.ti -1c
.RI "void \fBsp_toplistbrowse_add_ref\fP (\fBsp_toplistbrowse\fP *tlb)"
.br
.ti -1c
.RI "void \fBsp_toplistbrowse_release\fP (\fBsp_toplistbrowse\fP *tlb)"
.br
.ti -1c
.RI "int \fBsp_toplistbrowse_num_artists\fP (\fBsp_toplistbrowse\fP *tlb)"
.br
.ti -1c
.RI "\fBsp_artist\fP * \fBsp_toplistbrowse_artist\fP (\fBsp_toplistbrowse\fP *tlb, int index)"
.br
.ti -1c
.RI "int \fBsp_toplistbrowse_num_albums\fP (\fBsp_toplistbrowse\fP *tlb)"
.br
.ti -1c
.RI "\fBsp_album\fP * \fBsp_toplistbrowse_album\fP (\fBsp_toplistbrowse\fP *tlb, int index)"
.br
.ti -1c
.RI "int \fBsp_toplistbrowse_num_tracks\fP (\fBsp_toplistbrowse\fP *tlb)"
.br
.ti -1c
.RI "\fBsp_track\fP * \fBsp_toplistbrowse_track\fP (\fBsp_toplistbrowse\fP *tlb, int index)"
.br
.ti -1c
.RI "int \fBsp_toplistbrowse_backend_request_duration\fP (\fBsp_toplistbrowse\fP *tlb)"
.br
.in -1c
.SH "Define Documentation"
.PP 
.SS "#define \fBSP_TOPLIST_REGION\fP(a, b)   ((a) << 8 | (b))"
Convenience macro to create a toplist region\&. Toplist regions are ISO 3166-1 country codes (in uppercase) encoded in an integer\&. There are also some reserved codes used to denote non-country regions\&. See sp_toplistregion
.PP
Example: SP_TOPLIST_REGION('S', 'E') for Sweden 
.PP
\fBExamples: \fP
.in +1c
\fBtoplist\&.c\fP\&.
.SH "Typedef Documentation"
.PP 
.SS "typedef void \fBtoplistbrowse_complete_cb\fP(\fBsp_toplistbrowse\fP *result, void *userdata)"
The type of a callback used in \fBsp_toplistbrowse_create()\fP
.PP
When the callback is called, the metadata of all tracks belonging to it will have been loaded, so \fBsp_track_is_loaded()\fP will return non-zero\&. The same goes for the similar toplist data\&.
.PP
\fBParameters:\fP
.RS 4
\fIresult\fP The same pointer returned by \fBsp_toplistbrowse_create()\fP 
.br
\fIuserdata\fP The opaque pointer given to \fBsp_toplistbrowse_create()\fP 
.RE
.PP

.SH "Enumeration Type Documentation"
.PP 
.SS "enum \fBsp_toplistregion\fP"
Special toplist regions 
.PP
\fBEnumerator: \fP
.in +1c
.TP
\fB\fISP_TOPLIST_REGION_EVERYWHERE \fP\fP
Global toplist\&. 
.TP
\fB\fISP_TOPLIST_REGION_USER \fP\fP
Toplist for a given user\&. 
.SS "enum \fBsp_toplisttype\fP"
Toplist types 
.PP
\fBEnumerator: \fP
.in +1c
.TP
\fB\fISP_TOPLIST_TYPE_ARTISTS \fP\fP
Top artists\&. 
.TP
\fB\fISP_TOPLIST_TYPE_ALBUMS \fP\fP
Top albums\&. 
.TP
\fB\fISP_TOPLIST_TYPE_TRACKS \fP\fP
Top tracks\&. 
.SH "Function Documentation"
.PP 
.SS "void \fBsp_toplistbrowse_add_ref\fP (\fBsp_toplistbrowse\fP *tlb)"
Increase the reference count of an toplist browse result
.PP
\fBParameters:\fP
.RS 4
\fItlb\fP The toplist browse result object 
.RE
.PP

.SS "\fBsp_album\fP* \fBsp_toplistbrowse_album\fP (\fBsp_toplistbrowse\fP *tlb, intindex)"
Return the album at the given index in the given toplist browse object
.PP
\fBParameters:\fP
.RS 4
\fItlb\fP Toplist object 
.br
\fIindex\fP Index of the wanted album\&. Should be in the interval [0, \fBsp_toplistbrowse_num_albums()\fP - 1]
.RE
.PP
\fBReturns:\fP
.RS 4
The album at the given index in the given toplist browse object 
.RE
.PP

.PP
\fBExamples: \fP
.in +1c
\fBtoplist\&.c\fP\&.
.SS "\fBsp_artist\fP* \fBsp_toplistbrowse_artist\fP (\fBsp_toplistbrowse\fP *tlb, intindex)"
Return the artist at the given index in the given toplist browse object
.PP
\fBParameters:\fP
.RS 4
\fItlb\fP Toplist object 
.br
\fIindex\fP Index of the wanted artist\&. Should be in the interval [0, \fBsp_toplistbrowse_num_artists()\fP - 1]
.RE
.PP
\fBReturns:\fP
.RS 4
The artist at the given index in the given toplist browse object 
.RE
.PP

.PP
\fBExamples: \fP
.in +1c
\fBtoplist\&.c\fP\&.
.SS "int \fBsp_toplistbrowse_backend_request_duration\fP (\fBsp_toplistbrowse\fP *tlb)"
Return the time (in ms) that was spent waiting for the Spotify backend to serve the request
.PP
\fBParameters:\fP
.RS 4
\fItlb\fP Toplist object
.RE
.PP
\fBReturns:\fP
.RS 4
-1 if the request was served from the local cache If the result is not yet loaded the return value is undefined 
.RE
.PP

.SS "\fBsp_toplistbrowse\fP* \fBsp_toplistbrowse_create\fP (\fBsp_session\fP *session, \fBsp_toplisttype\fPtype, \fBsp_toplistregion\fPregion, const char *username, \fBtoplistbrowse_complete_cb\fP *callback, void *userdata)"
Initiate a request for browsing an toplist
.PP
The user is responsible for freeing the returned toplist browse using \fBsp_toplistbrowse_release()\fP\&. This can be done in the callback\&.
.PP
\fBParameters:\fP
.RS 4
\fIsession\fP Session object 
.br
\fItype\fP Type of toplist to be browsed\&. see the sp_toplisttype enum for possible values 
.br
\fIregion\fP Region\&. see sp_toplistregion enum\&. Country specific regions are coded as two chars in an integer\&. Sweden would correspond to 'S' << 8 | 'E' 
.br
\fIusername\fP If region is SP_TOPLIST_REGION_USER this specifies which user to get toplists for\&. NULL means the logged in user\&. 
.br
\fIcallback\fP Callback to be invoked when browsing has been completed\&. Pass NULL if you are not interested in this event\&. 
.br
\fIuserdata\fP Userdata passed to callback\&.
.RE
.PP
\fBReturns:\fP
.RS 4
Toplist browse object
.RE
.PP
\fBSee also:\fP
.RS 4
\fBtoplistbrowse_complete_cb\fP 
.RE
.PP

.PP
\fBExamples: \fP
.in +1c
\fBtoplist\&.c\fP\&.
.SS "\fBsp_error\fP \fBsp_toplistbrowse_error\fP (\fBsp_toplistbrowse\fP *tlb)"
Check if browsing returned an error code\&.
.PP
\fBParameters:\fP
.RS 4
\fItlb\fP Toplist browse object
.RE
.PP
\fBReturns:\fP
.RS 4
One of the following errors, from \fBsp_error\fP SP_ERROR_OK SP_ERROR_IS_LOADING SP_ERROR_OTHER_PERMANENT SP_ERROR_OTHER_TRANSIENT 
.RE
.PP

.SS "bool \fBsp_toplistbrowse_is_loaded\fP (\fBsp_toplistbrowse\fP *tlb)"
Check if an toplist browse request is completed
.PP
\fBParameters:\fP
.RS 4
\fItlb\fP Toplist browse object
.RE
.PP
\fBReturns:\fP
.RS 4
True if browsing is completed, false if not 
.RE
.PP

.SS "int \fBsp_toplistbrowse_num_albums\fP (\fBsp_toplistbrowse\fP *tlb)"
Given an toplist browse object, return number of albums
.PP
\fBParameters:\fP
.RS 4
\fItlb\fP Toplist browse object
.RE
.PP
\fBReturns:\fP
.RS 4
Number of albums on toplist 
.RE
.PP

.PP
\fBExamples: \fP
.in +1c
\fBtoplist\&.c\fP\&.
.SS "int \fBsp_toplistbrowse_num_artists\fP (\fBsp_toplistbrowse\fP *tlb)"
Given an toplist browse object, return number of artists
.PP
\fBParameters:\fP
.RS 4
\fItlb\fP Toplist browse object
.RE
.PP
\fBReturns:\fP
.RS 4
Number of artists on toplist 
.RE
.PP

.PP
\fBExamples: \fP
.in +1c
\fBtoplist\&.c\fP\&.
.SS "int \fBsp_toplistbrowse_num_tracks\fP (\fBsp_toplistbrowse\fP *tlb)"
Given an toplist browse object, return number of tracks
.PP
\fBParameters:\fP
.RS 4
\fItlb\fP Toplist browse object
.RE
.PP
\fBReturns:\fP
.RS 4
Number of tracks on toplist 
.RE
.PP

.PP
\fBExamples: \fP
.in +1c
\fBtoplist\&.c\fP\&.
.SS "void \fBsp_toplistbrowse_release\fP (\fBsp_toplistbrowse\fP *tlb)"
Decrease the reference count of an toplist browse result
.PP
\fBParameters:\fP
.RS 4
\fItlb\fP The toplist browse result object 
.RE
.PP

.PP
\fBExamples: \fP
.in +1c
\fBtoplist\&.c\fP\&.
.SS "\fBsp_track\fP* \fBsp_toplistbrowse_track\fP (\fBsp_toplistbrowse\fP *tlb, intindex)"
Return the track at the given index in the given toplist browse object
.PP
\fBParameters:\fP
.RS 4
\fItlb\fP Toplist object 
.br
\fIindex\fP Index of the wanted track\&. Should be in the interval [0, \fBsp_toplistbrowse_num_tracks()\fP - 1]
.RE
.PP
\fBReturns:\fP
.RS 4
The track at the given index in the given toplist browse object 
.RE
.PP

.PP
\fBExamples: \fP
.in +1c
\fBtoplist\&.c\fP\&.
.SH "Author"
.PP 
Generated automatically by Doxygen for libspotify from the source code\&.
